主にVSCodeではじめるPython開発環境構築ガイド

nokomoro3

2023.10.12

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

こんちには。

データアナリティクス事業本部インテグレーション部機械学習チームの中村です。

今回は、Python開発を主な対象とした開発環境構築の方法をまとめてみたいと思います。

(2023-10-20 : 更新)
・以下の拡張機能を追加
　・Material Icon Theme
　・Conventional Commits
　・Git History
　・Python Test Explorer for Visual Studio Code
　・sqlfluff
　・Live Share
・コードアシスタントの章を追加

はじめに

主にPythonでの開発を始める際のオンボーディングに使用する前提の内容となっています。

社内でPythonの勉強会を何回か開催したのですが、その時の事前準備資料が元ネタとなっています。

https://github.com/cm-nakamura-shogo/python-training/blob/master/doc/lecture/prepare/README.md

またエディタとしてVSCodeを使用している前提となっていますので、ご容赦ください。

（エディタにこだわりがある方はおそらく上級者層かとおもいますので、本記事は必要な箇所のみ参考にして頂ければと思います）

開発環境

VSCodeの準備

以下から使用しているOSに該当するものを選んでダウンロードします。

https://code.visualstudio.com/download

私はWindows環境ですので、VSCodeUserSetup-x64-1.83.0.exeを今回ダウンロードしました。

インストーラーを実行してインストールします。

途中に出てくるチェックボックスは以下のようにチェックしました。（「Codeで開く」は意外と便利なので）

Python環境の構築

こちらにはいくつか選択肢があります。

お好きなものを選んで構築してください。（これ以外にもあると思います）

通常のPythonインストーラ + pip
- Download Python | Python.org
pyenv + venv + pip
- Python:venv + pyenvでの環境構築 - 無粋な日々に
pyenv + pipenv
- pyenvとpipenvで、快適Python生活（Windows向け）
pyenv + poetry
- pyenvとpoetryでディレクトリ毎にPython環境を切り替える手順＋ノウハウまとめ | DevelopersIO
- [Mac]Poetryがインストールできないときの回避策
Rye
- 【Pythonのパッケージ管理に悩む方へ】パッケージ管理ツールRyeを使ってみた | DevelopersIO

なお、個人的には「4. pyenv + poetry」と「5. Rye」を推しています。これらは手順がいくつか必要ですので、パッケージのバージョン管理等が不要で、最も簡易に始められるなら一旦「1. 通常のPythonインストーラ」でも良いと思います。（後で乗り換えも可能ですので）

フォントの設定

フォントはコード上でコード（英語）とコメント（日本語）をバランスよく表示できる「白源 (はくげん／HackGen)」を使用しています。

https://github.com/yuru7/HackGen

その他、等幅フォントの中では0とOがの違いや空白が分かりやすかったりという理由で使用しています。

フォントはお好みで良いと思います。

VSCodeの操作

ショートカット

以下に網羅的にまとまっています。

私も全ては把握できておらず使いこなせていないのですが、自分なりに使いそうなショートカットを整理してみました。

（Windows向けのショートカットで書いておりますので、ご了承ください。。。）

全般

キー	内容
Ctrl+K Ctrl+S	キーボードショートカット一覧を開く
Ctrl+P	指定ファイルを開く
Ctrl+Shift+P	コマンドパレットを表示
Ctrl+,	ユーザ設定を開く

これ以降、なんかショートカットが動かないな…と思われたらPC側の設定を確認するか、ショートカット一覧をご確認ください。

ウィンドウ関連

ウィンドウ - エディタ - タブという階層構造になっている、として説明しています。

キー	内容
Ctrl+Tab	タブ移動
Ctrl+PgUp	次のタブに移動
Ctrl+PgDn	前のタブに移動
Ctrl+W	タブを閉じる
Ctrl+Shift+T	閉じたタブをもう一度開く
Ctrl+\|	エディターを左右に分割
Ctrl+数字	カーソルを別のエディターに移動(ない場合は作成)
Ctrl+Alt+Left	タブを別のエディターに移動
Ctrl+Alt+Right	タブを別のエディターに移動
Ctrl+Alt+Up	タブを別のエディターに移動
Ctrl+Alt+Down	タブを別のエディターに移動
Ctrl+N	ファイルの新規作成
Ctrl+K Ctrl+W	すべてのタブ(エディター)を閉じる
Ctrk+K P	アクティブなファイルのパスをコピー
Ctrk+K R	アクティブなファイルをエクスプローラーで表示
Ctrl+Shift+=	ズームイン
Ctrl+Shift+-	ズームアウト

ターミナル

キー	内容
Ctrl+J	ターミナルウィンドウを開く
Ctrl+Shift+`	ターミナルウィンドウを増やす

編集

キー	内容
Ctrl+X	行の切り取り (未選択時)
Ctrl+C	行のコピー (未選択時)
Alt+Down	カーソル行を下に移動
Alt+Up	カーソル行を上に移動
Shift+Alt+Down	カーソル行を下にコピー
Shift+Alt+Up	カーソル行を上にコピー
Ctrl+/	コメント・アンコメントの切り替え
Shift+Alt+F	コードをフォーマット
F12	関数等の定義に移動

カーソル移動

キー	内容
Ctrl+Left	前の単語にカーソル移動
Ctrl+Right	次の単語にカーソル移動
Home	行の先頭に移動
End	行の末尾に移動
Ctrl+Home	ファイル先頭にカーソル移動
Ctrl+End	ファイル末尾にカーソル移動
Ctrl+G	指定行に移動

検索

キー	内容
Ctrl+F	検索
Ctrl+H	置換
F3	次に移動 (検索時)
Shift+F3	前に移動 (検索時)

マルチカーソル

キー	内容
Ctrl+Alt+Down	カーソルを下に追加
Ctrl+Alt+Up	カーソルを上に追加
Ctrl+D	次のマッチをカーソルに追加 (選択時)
Ctrl+Shift+L	全マッチをカーソルに追加 (選択時)

ファイル比較

VSCodeのエクスプローラで、ファイル２つを選択して右クリックメニューから「選択項目を比較」で比較することができます。

また右クリックで、「比較対象の選択」をした後に「選択項目を比較」でも比較することも可能です。

VSCodeのSnippetの使い方

VSCodeのSnippetも便利です。似たような構造のクラスを実装する場合などや、プロジェクト共通で使いがちな書き方というものをSnippetに登録して、効率化することができます。

また、変数を持たせておくこともできます。この場合、Snippetを呼び出した後に変数部分にカーソルがあたるので、そこで変数部分をタイピングできます。

詳細は以下のリンクをご覧ください。

また後述するSnippet Generatorという拡張機能では、コードからSnippetを作成することも可能です。

Pythonの対話環境

Pythonはそのままでも対話環境として実行できますが、これとは別にIPythonやptpython、bpythonなども存在するようです。

pipなどで簡単に入れることができ、デフォルトよりは効率よく操作ができると思いますので、自身にあった環境で入れてみてご確認ください。

pip install ipython
pip install ptpython
pip install bpython # Windowsでは未対応

ノートブック環境

ノートブック環境を構築するにもいくつか方法があります。

VSCode + ipykernel

ipykernelをpip等でインストールします。

pip install ipykernel

その後空白の.ipynbファイルを作成し、VSCode上で開けばノートブックとして使用できます。

Jupyter Notebook

Jupyter Notebookをインストールします。

pip install notebook

その後、以下のように起動すればOKです。

jupyter-notebook

Jupyter Lab

Jupyter Labをインストールします。

pip install jupyterlab

その後、以下のように起動すればOKです。

jupyter-lab

VSCode拡張機能

ここからはVSCodeの拡張機能を紹介していきます。良いなと思ったものを入れていけばよいかと思います。

（一部Pythonとは無関係なものも含まれますがご了承ください）

言語パック

Japanese Language Pack for Visual Studio Code

VSCodeの表示を日本語化する拡張機能です。

時々英語に戻るなどが発生した場合は都度以下で設定し直せばOKです。

「Ctrl+Shift+P」で押して「コマンドパレット」を表示
「display」と入力して「Configure Display Language」コマンドを実行
するとインストールされている言語の一覧がロケールごとに表示される
言語を切り替えるには、「日本語 (ja)」を選択

編集補助

Insert Numbers

マルチカーソルで文字列をフォーマット指定して連番を入力できる拡張機能です。

デフォルトで使うフォーマットを設定しておくと便利です（以下設定例です）。

    "insertnum.formatstr": "%02d",
    "insertnum.start": 1,
    "insertnum.step": 1,

change-case

選択した範囲を特定のcaseに変更することができます。

大文字小文字に始まり、camelCase、snake_case、kebab-caseなどに変換できます。

Snippet Generator

コードからSnippetを作成するための拡張機能です。

視認性

Material Icon Theme

VSCode上でアイコンをデコる拡張機能です。ここは好みに応じて選択すべき部分かと思いますが最近はこの機能に落ち着いています。

他にもアイコン関連の拡張機能はたくさんありますので、お気に入りのものを探してみて下さい。

Visual Studio Code のファイルアイコンを変える #VisualStudioCode - Qiita

indent-rainbow

インデントを色分けしてくれる拡張機能です。4色を繰り返してインデントを表現します。

Trailing Spaces

空白を可視化する拡張機能です。以下のように可視性高く余計な空白を分かりやすく表示できます。

Error Lens

エラーの内容をエディタで見えるようにしてくれる（マウスオーバーする必要がない）拡張機能です。

後述のlinterと組み合わせると強力に機能すると思います。

Blockman - Highlight Nested Code Blocks

ネストされたコードブロックを分かりやすく囲って表示する拡張機能です。

Git

事前にgitのインストール（Windows環境の場合、Git Bash）が必要かもしれません。うまく動かなければお試しください。

https://gitforwindows.org/

Conventional Commits

コミットメッセージをルール付けして残していくことを助ける拡張機能となっています。

くわしい説明は以下のページに記載があります。

Conventional Commits

この機能を使うと、おおむね以下に沿ったコミットメッセージにすることができます。

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

スコープはapiなどの粒度でチケット等の粒度とは異なっています。

optionalを使わない場合は、以下のようにsettings.jsonをしておくことで簡易に使用することも可能です。

{
    "conventionalCommits.promptScopes": false,
    "conventionalCommits.promptFooter": false,
    "conventionalCommits.promptBody": false,
    "conventionalCommits.gitmoji": false,
}

Git Graph

Gitのコミット履歴をツリー状のグラフで確認することができます。

また多くのGit操作がGUIで実行できるようになっています。

（Gitコマンドをなかなか覚えられない要因になりがちです汗）

GitLens

もう一つGitの拡張機能です。私は、主にブランチ同士の差分確認やファイル別の変更履歴の確認に主に使用します。

機能はかなり豊富なようなのですが、ちょっと私自身が使いこなせてないので、色々試行錯誤されてみて下されば幸いです。

以下もご参考にされてください。

VSCodeの拡張機能「GitLens」で快適なGitライフを手に入れよう！ #Git - Qiita

Git History

こちらもGitの拡張機能です。これもファイル履歴が確認可能なものですが、GitLensと比較してみてお好みを使うと良いかと思います。

Python

Python開発の基本の拡張機能です。

（いつからかPylance等もこの拡張機能に含まれるようになりましたね）

これらを入れておくことが後述のlinterやformatterの大前提となります。

autoDocstring

Pythonのdocstringを自動生成できる拡張機能です。

docstringとは以下のようなものです。

型ヒントを書いておくと、それも考慮してdocstringを生成しますので便利です。

Python Test Explorer for Visual Studio Code

こちらはpytestをGUIから実行・確認することができる機能となっています。

以下に詳しい解説がございますのでご覧ください。

Pytestを使ってみる（その２：VSCode拡張機能編） | 豆蔵デベロッパーサイト

Pythonコードチェック

コードチェックですが、大きく分けてlinterとformatterがあります。

ここで主にフォーカスするのは以下の４つです。

linter : ソースコードを静的解析してチェックするツールで指摘するのみ
- Ruff : PEP8に従っているかなどのチェック (flake8のようなもの)
- Mypy : 型ヒントによる型チェック
formatter : スタイルを自動的に修正するツール
- Black : PEP8に従ったスタイルフォーマット
- isort : インポート順のフォーマット

現在では上記それぞれVSCodeの拡張機能があり、pip等でインストールせずとも各ツールを動かすことが可能になっています。

Ruff
- Ruff
Mypy
- Mypy Type Checker
Black
- Black Formatter
isort
- isort

これらの拡張機能をインストール後、settings.jsonを必要に応じて設定します。

設定例は以下となります。

    "": {
        "editor.defaultFormatter": "ms-python.black-formatter",
        "editor.formatOnSave": true,
        "editor.codeActionsOnSave": {
            "source.organizeImports": true
        }
    },
    "ruff.organizeImports": false,
    "isort.args": [
        "--profile",
        "black"
    ],
    "python.analysis.typeCheckingMode": "strict",
    "ruff.format.args": [
        "--config=pyproject.toml"
    ],

settings.jsonですが、ユーザ側にするかかワークスペース側にするかは、状況に合わせて設定されてください。

こちらの設定で、Blackとisortのformatterは動くようになるかと思います。

ワークスペース側で設定したのになぜかフォーマッタが動かないな、などと思ったらユーザ側に無効化の設定がないかを確認してみてください（私がそうでした）。

formatter側は今回特にカスタマイズしていないので、以降linter側の設定を説明していきます。

Ruffについて

Ruffは比較的新しいlinterで、先発のlinterより高速に動作することが特徴です。

https://docs.astral.sh/ruff/

（Rust製のツールは、Python周りでも増えてきましたね）

Ruffの設定について

保存時にRuffのクイックフィックスを強制的に動かすなども可能ですが、コーディング中に動かれるのは厳しすぎることと、linterの領分を超えていると考えたため、その設定はしていません。

またRuffの設定はpyproject.tomlを見に行くようにしています。

    "ruff.format.args": [
        "--config=pyproject.toml"
    ],

pyproject.tomlの記載は以下のようにできます（こちらもあくまで設定例）。

[tool.ruff]
select = [
  "E",   # pycodestyle
  "F",   # pyflakes
  "D",   # pydocstyle
]
ignore = ["D415"]

[tool.ruff.pydocstyle]
convention = "google"

selectはどのルールを適用するかを記述する部分で、デフォルトは["E", "F"]なのですが、今回docstringを書くように強制したかったので、"D"も追加しています。

設定のデフォルトは以下に記載があります。

https://docs.astral.sh/ruff/settings/#select

"D415"を無視しているのは、docstringをperiodなどで終わるようにするルールがあったため、お試しで無効化にしました。

ルールは非常に多いので、調整は実際にやりながら適切な設定を探してみてください。各ルールの詳細は以下をご参照ください。

https://docs.astral.sh/ruff/rules/

また、BlackとRuffの設定が一致するようにしておくと統一的で良いかと思います。

Mypyの設定について

Mypyが関わる設定はsettings.jsonの以下となります。

    "python.analysis.typeCheckingMode": "strict",

今回basicでは、型ヒントの未記入を警告できなかったためstrictに設定してみました。ここも必要に応じて調整されてください。

参考記事

linterとformatterに関連する参考記事です。

SQLコードチェック

SQLのコードチェックをする拡張機能を紹介します。

sqlfluff

SQLのlinter、formatterであるSQLFluffをVSCodeで動作させる拡張機能です。

拡張機能単体では動作せず、sqlfluffをコマンドで実行できる必要がありますので、以下で確認して入っていない場合はpipやHomebrew等でセットアップしてください。

sqlfluff --version

# sqlfluff, version 2.3.4

dialectの設定もでき、以下のようにathena、bigqueryなどにも対応しています。

テキスト編集

Markdown Preview Enhanced

Markdownのプレビュー表示が見やすくなる拡張機能です。

数式を描画したり、章立てのIndexが表示したりすることができます。

Markdown PDF

MarkdownをPDF変換する拡張機能です。

Paste Image

クリップボードからmarkdownに画像を張り付けられる拡張機能です。

スクリーンショットとの連携で結構使い勝手が良いです。

私も以下の設定で使用しています。

Markdownでスクショ画像をペーストする(VS Code)

    "pasteImage.namePrefix": "${currentFileNameWithoutExt}_",
    "pasteImage.path": "${currentFileDir}/img",
    "pasteImage.prefix": "./",
    "pasteImage.showFilePathConfirmInputBox": true,
    "pasteImage.filePathConfirmInputBoxMode": "onlyName",